This crate defines Finite Field traits and useful abstraction models that follow these traits.
Implementations of concrete finite fields for some popular elliptic curves can be found in arkworks-rs/curves
under arkworks-rs/curves/<your favourite curve>/src/fields/
.
This crate contains two types of traits:
Field
traits: These define interfaces for manipulating field elements, such as addition, multiplication, inverses, square roots, and more.- Field
Config
s: specifies the parameters defining the field in question. For extension fields, it also provides additional functionality required for the field, such as operations involving a (cubic or quadratic) non-residue used for constructing the field (NONRESIDUE
).
The available field traits are:
Field
- Interface for a generic finite field.FftField
- Exposes methods that allow for performing efficient FFTs on field elements.PrimeField
- Field with a primep
number of elements, also referred to asFp
.
The models implemented are:
Quadratic Extension
QuadExtField
- Struct representing a quadratic extension field, in this case holding two base field elementsQuadExtConfig
- Trait defining the necessary parameters needed to instantiate a Quadratic Extension Field
Cubic Extension
CubicExtField
- Struct representing a cubic extension field, holds three base field elementsCubicExtConfig
- Trait defining the necessary parameters needed to instantiate a Cubic Extension Field
The above two models serve as abstractions for constructing the extension fields Fp^m
directly (i.e. m
equal 2 or 3) or for creating extension towers to arrive at higher m
. The latter is done by applying the extensions iteratively, e.g. cubic extension over a quadratic extension field.
Fp2
- Quadratic extension directly on the prime field, i.e.BaseField == BasePrimeField
Fp3
- Cubic extension directly on the prime field, i.e.BaseField == BasePrimeField
Fp6_2over3
- Extension tower: quadratic extension on a cubic extension field, i.e.BaseField = Fp3
, butBasePrimeField = Fp
.Fp6_3over2
- Extension tower, similar to the above except that the towering order is reversed: it's a cubic extension on a quadratic extension field, i.e.BaseField = Fp2
, butBasePrimeField = Fp
. Only this latter one is exported by default asFp6
.Fp12_2over3over2
- Extension tower: quadratic extension ofFp6_3over2
, i.e.BaseField = Fp6
.
Usage
There are two important traits when working with finite fields: [Field
],
and [PrimeField
]. Let's explore these via examples.
[Field
]
The [Field
] trait provides a generic interface for any finite field.
Types implementing [Field
] support common field operations
such as addition, subtraction, multiplication, and inverses.
use Field;
// We'll use a field associated with the BLS12-381 pairing-friendly
// group for this example.
use Fq2 as F;
// `ark-std` is a utility crate that enables `arkworks` libraries
// to easily support `std` and `no_std` workloads, and also re-exports
// useful crates that should be common across the entire ecosystem, such as `rand`.
use ;
let mut rng = test_rng;
// Let's sample uniformly random field elements:
let a = rand;
let b = rand;
// We can add...
let c = a + b;
// ... subtract ...
let d = a - b;
// ... double elements ...
assert_eq!;
// ... multiply ...
let e = c * d;
// ... square elements ...
assert_eq!;
// ... and compute inverses ...
assert_eq!; // have to to unwrap, as `a` could be zero.
In some cases, it is useful to be able to compute square roots of field elements
(e.g.: for point compression of elliptic curve elements).
To support this, users can implement the sqrt
-related methods for their field type. This method
is already implemented for prime fields (see below), and also for quadratic extension fields.
The sqrt
-related methods can be used as follows:
use Field;
// As before, we'll use a field associated with the BLS12-381 pairing-friendly
// group for this example.
use Fq2 as F;
use ;
let mut rng = test_rng;
let a = rand;
// We can check if a field element is a square by computing its Legendre symbol...
if a.legendre.is_qr else
[PrimeField
]
If the field is of prime order, then users can choose
to implement the [PrimeField
] trait for it. This provides access to the following
additional APIs:
use ;
// Now we'll use the prime field underlying the BLS12-381 G1 curve.
use Fq as F;
use ;
let mut rng = test_rng;
let a = rand;
// We can access the prime modulus associated with `F`:
let modulus = MODULUS;
assert_eq!;
// We can convert field elements to integers in the range [0, MODULUS - 1]:
let one: BigUint = one.into;
assert_eq!;
// We can construct field elements from an arbitrary sequence of bytes:
let n = from_le_bytes_mod_order;
assert_eq!;